n8n Guía paso a paso

Guía visual para poner en marcha el nodo Fideltour de n8n desde cero: instalación, credenciales, un primer workflow que consulta HotelDataHub y un workflow que arranca automáticamente con un webhook de Fideltour. La referencia completa de recursos, operaciones y eventos está en la página n8n.

Tabla de contenidos¶

• Antes de empezar
• 1. Instalar el community node
• 2. Crear la credencial Fideltour API
• 3. Primer workflow: consultar un contacto
• 4. Workflow con trigger: reaccionar a un contacto creado
• 5. Comprobar la suscripción en HotelDataHub
• Problemas frecuentes

Antes de empezar¶

Se necesita:

• Una instancia de n8n (self-hosted o n8n Cloud) con permisos de administrador para instalar community nodes. Las capturas de esta guía corresponden a n8n 2.31.
• Un usuario API de HotelDataHub (ApiUser) con los permisos contacts y movements (y segments si se van a usar los triggers de audiencias). Se solicita a hoteldatahub@fideltour.com junto con el código de cadena (hotel_chain) y los identificadores de hotel.
• Para los triggers, la instancia de n8n debe ser accesible desde internet: HotelDataHub llama a la URL del webhook de n8n cada vez que ocurre un evento.

1. Instalar el community node¶

1. En n8n, abrir Settings → Community nodes (icono de engranaje, abajo a la izquierda) y pulsar Install a community node.

2. Escribir el nombre del paquete, n8n-nodes-fideltour, marcar la casilla de aceptación e Install. n8n descarga el paquete de npm y registra los nodos sin necesidad de reiniciar.

Al terminar, el paquete aparece en la lista con sus dos nodos: Fideltour (acciones) y Fideltour Trigger (eventos). Para actualizar a una versión nueva, usar el menú ⋮ del paquete → Update.

n8n Cloud: la instalación se hace igual desde Settings → Community nodes. Si el paquete todavía no aparece como verificado, hay que tener activada la opción de nodos no verificados en la instancia.

2. Crear la credencial Fideltour API¶

1. Ir a Credentials (en el panel Overview o desde el menú lateral) y pulsar Create credential. Buscar Fideltour API y pulsar Continue.

2. Rellenar los tres campos:

El campo Session Token no se rellena: el nodo hace login contra POST /api/v1/login/ y guarda ahí el JWT, renovándolo automáticamente cuando caduca (24 h).

3. Pulsar Save. n8n prueba la credencial haciendo un GET /api/v1/entries/; si el usuario y la contraseña son correctos y el usuario tiene el permiso movements, aparece Connection tested successfully.

Conviene llamar a la credencial Fideltour API: es el nombre que usan los workflows de ejemplo de esta guía y de la página n8n, así se pueden pegar directamente sin reasignar credenciales.

3. Primer workflow: consultar un contacto¶

Objetivo: un workflow manual que busca un contacto en HotelDataHub por su email. Es la forma más rápida de comprobar que la instalación y la credencial funcionan.

1. Crear un workflow nuevo (+ → Workflow) y añadir como primer paso el trigger Manual (When clicking 'Execute workflow').

2. Pulsar el botón + (arriba a la derecha del lienzo) y buscar Fideltour. Aparece el nodo con el icono FT.

3. Al seleccionarlo se muestran las acciones agrupadas por recurso (Contact, Loyalty, Movement, Web Form). Elegir Get many contacts.

El nodo queda conectado al trigger manual:

4. Configurar el nodo: seleccionar la credencial Fideltour API, dejar Resource = Contact y Operation = Get Many, y en Filters añadir Email con el email a buscar. Limit y Offset controlan la paginación (limit/offset de la API).

5. Pulsar Execute step. La salida (OUTPUT) muestra la respuesta de GET /api/v1/contacts/: count, next, previous y results con la ficha completa de cada contacto (id, nombre, email, idioma, país, nivel loyalty, consentimientos…).

6. Al cerrar el panel, el lienzo marca ambos nodos en verde con el número de items que han pasado por cada conexión.

El ID que devuelve este nodo (results[0].id) es el que necesitan el resto de operaciones (Contact → Update, Movement → Create, Loyalty → Sign In…): se referencia con una expresión como {{ $json.results[0].id }}.

Workflow completo (pegar en el lienzo con Ctrl+V):

{
  "name": "Fideltour - Buscar contacto por email",
  "nodes": [
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "resource": "contact",
        "operation": "getAll",
        "limit": 10,
        "filters": { "email": "cliente@example.com" }
      },
      "type": "n8n-nodes-fideltour.fideltour",
      "typeVersion": 1,
      "position": [260, 0],
      "name": "Get Many Contacts",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    }
  ],
  "connections": {
    "When clicking 'Execute workflow'": {
      "main": [[{ "node": "Get Many Contacts", "type": "main", "index": 0 }]]
    }
  }
}

4. Workflow con trigger: reaccionar a un contacto creado¶

Objetivo: que n8n arranque un workflow cada vez que se crea un contacto en Fideltour. El nodo Fideltour Trigger registra por sí solo la suscripción (REST hook) en HotelDataHub al publicar el workflow y la elimina al despublicarlo.

1. Crear un workflow nuevo, pulsar Add first step, buscar Fideltour y elegir Fideltour Trigger (en la sección Triggers). Añadir después cualquier nodo que consuma el evento; en el ejemplo, un nodo Edit Fields que prepara un saludo a partir del contacto.

2. Abrir el trigger, seleccionar la credencial Fideltour API y el Event deseado (aquí Contact Created). Desplegando Webhook URLs se ven las dos URLs que n8n expone para este nodo:

• Test URL (/webhook-test/...): solo escucha mientras se pulsa Execute step / Test this trigger en el editor.
• Production URL (/webhook/...): es la que el nodo registra en HotelDataHub cuando el workflow está publicado.

3. Pulsar Publish (en versiones anteriores de n8n, el interruptor Active). Se pide un nombre de versión y, al confirmar, n8n activa el workflow.

En ese momento el nodo llama a POST /api/v1/webhooks/zapier-webhooks-subscriptions/ con la Production URL y el tipo de evento (5 = Contact Created). Si la llamada falla (credencial sin permiso contacts, URL no pública…), n8n muestra el error y no publica el workflow.

4. A partir de aquí, cada contacto creado en Fideltour genera una ejecución. En la pestaña Executions se listan; al abrir una, el panel Logs muestra el payload recibido por el trigger (la ficha del contacto más hotel_chain) y la salida de cada nodo.

Workflow completo:

{
  "name": "Fideltour - Contacto creado",
  "nodes": [
    {
      "parameters": { "event": 5 },
      "type": "n8n-nodes-fideltour.fideltourTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "name": "Fideltour Trigger",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            { "id": "x1", "name": "contact_id", "value": "={{ $json.id }}", "type": "number" },
            { "id": "x2", "name": "email", "value": "={{ $json.email }}", "type": "string" },
            { "id": "x3", "name": "saludo", "value": "=Hola {{ $json.name }} {{ $json.surname }}, bienvenido a {{ $json.hotel_chain }}", "type": "string" }
          ]
        },
        "options": {}
      },
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [260, 0],
      "name": "Preparar datos"
    }
  ],
  "connections": {
    "Fideltour Trigger": {
      "main": [[{ "node": "Preparar datos", "type": "main", "index": 0 }]]
    }
  }
}

Probar sin esperar a un evento real: con el workflow publicado, un POST a la Production URL con un JSON en el body genera una ejecución idéntica a la que produciría HotelDataHub. Es útil para desarrollar el resto del workflow con un payload de ejemplo. Los payloads de cada evento están descritos en la página de Zapier (son los mismos).

5. Comprobar la suscripción en HotelDataHub¶

La suscripción que crea el trigger se puede consultar con el mismo usuario API (cada ApiUser solo ve las suyas):

GET https://app.hoteldatahub.io/api/v1/webhooks/zapier-webhooks-subscriptions/
Authorization: Token <jwt>

{
  "count": 1,
  "results": [
    {
      "id": 61,
      "url": "https://n8n.mi-hotel.com/webhook/3f7c2a1e-5b7d-4c1e-9a0b-6d2e8f1a2b3c/webhook",
      "type": 5
    }
  ]
}

Al despublicar el workflow (o borrarlo), el nodo hace DELETE .../zapier-webhooks-subscriptions/{id}/ y la suscripción desaparece. Si un workflow se elimina con la instancia de n8n apagada, la suscripción puede quedar huérfana: en ese caso se borra a mano con la misma llamada DELETE.

Para que los eventos de contactos y movimientos lleguen a HotelDataHub (y de ahí a n8n), Fideltour debe tener configurados los webhooks genéricos del cliente, igual que para Zapier (ver Suscripción REST hooks).

Problemas frecuentes¶